package io.gitee.luoyuan800.tool.llm.web;

import java.util.Map;
import java.util.stream.Stream;

/**
 * 用于发送 RESTful 请求的客户端接口。
 * 提供了标准的 POST 请求和流式 POST 请求方法。
 * @author Luoyuan/ Gavin
 */
public interface RestfulClient {
    /**
     * 发送一个 POST 请求到指定的 URL，并返回响应结果。
     *
     * @param <T> 请求体的类型
     * @param <R> 响应体的类型
     * @param url 请求的目标 URL
     * @param header 请求头信息，以键值对形式表示
     * @param requestBody 请求体对象
     * @param responseType 期望的响应类型 Class 对象
     * @return 解析后的响应对象
     * @throws IllegalArgumentException 如果参数不合法（如 URL 为空）
     */
    <T, R> R post(String url, Map<String, String> header, T requestBody, Class<R> responseType);

    /**
     * 发送一个流式 POST 请求到指定的 URL，并返回响应结果的流。
     * 适用于处理服务器端推送的流式响应。
     *
     * @param <T> 请求体的类型
     * @param <R> 响应体的类型
     * @param url 请求的目标 URL
     * @param header 请求头信息，以键值对形式表示
     * @param requestBody 请求体对象
     * @param responseType 期望的响应类型 Class 对象
     * @return 响应对象的流
     * @throws IllegalArgumentException 如果参数不合法（如 URL 为空）
     */
    <T, R> Stream<R> postStream(String url, Map<String, String> header, T requestBody, Class<R> responseType);
}
